Collection of Tools & Utilities/Collection of Tools and Utilities.iso/tex/atcomp16.zip/@COMPARE.DOC

Text File | 1994-01-26 | 27KB | 554 lines

                        ╔═════════════════════════╗
════════════════════════╣  @Compare, version 1.6  ╠════════════════════════
════════════════════════╣     Brian C. Madsen     ╠════════════════════════
                        ╚═════════════════════════╝



COPYRIGHTS AND DISCLAIMERS:  ══════════════════════════════════════════════

@Compare is copyright 1988-1994 by Brian C. Madsen.  This copyright applies
to the source code, the executable program, and this documentation, and to
all past and future versions of this program which have been or will be
produced by the author.  All rights are reserved, including the right to
market this product for profit.  Although @Compare is copyrighted, it may
be freely distributed, so long as it is accompanied by this documentation,
and so long as neither the program nor this documentation is altered in any
way.  The author will not be held legally responsible for unforseen side
effects arising from the use of this program, and your use of this program
constitutes your agreement to this copyright notice and disclaimer.



DESCRIPTION:  ═════════════════════════════════════════════════════════════

@Compare works on Ascii files which are roughly similar to each other (for
example, a .PAS and its .BAK file; a document and an earlier version of
the same document; or data created via double data entry.)  Files to be
compared may be of unlimited length.

@Compare matches up the two files, displaying them side by side, and dis-
playing the similarities and differences between them.  Equal lines are
marked by an equal sign on both sides of the screen; discrepancies in
similar but unequal lines are highlighted; and lines which exist in one
file and which have no corresponding counterpart in the other file are
displayed as such.



CHANGES SINCE VERSION 1.5 ═════════════════════════════════════════════════

The following features have been added, and problems resolved, since the
last release of @Compare.  Feel free to skip this section if you are new
to @Compare.

1.  A bug has been fixed which caused range check errors when very large
    files were @Compared, or when very long stretches occurred between
    differences in files.

2.  My address has changed.

3.  Version number and copyright dates have been updated throughout.



OPERATION:  ═══════════════════════════════════════════════════════════════

    At a glance:  @Compare [-PFMTHARCLEBQ] [filename.one [filename.two]]

@Compare accepts an options parameter and the names of one or two files as
command line arguments.  The options parameter, if it is present, must be
the first in the list of command line parameters, and it must begin with a
/ or -.  If none of these parameters is given, a usage reminder is printed
and the program prompts for them.

Legal options are as follows:

    P -- directs output to the printer.

    F -- directs output to a file.  The program prompts for the name of
         this file, which defaults to @Compare.@@@. The file will be over-
         written if it already exists. The F parameter takes precedence
         over the P parameter if both are specified.

    M -- writes to the screen in black and white, instead of the default
         colors.  This is intended for use with monochrome monitors.

    T -- suppresses the printing of the program's title.

    H -- suppresses highlighting of discrepancies in unequal lines.  This
         highlighting is done on a character by character basis.  It shows
         up as underlining on the printer, and does not show up in the
         @Compare.@@@ file.

    A -- replaces all occurrences of extended Ascii graphics characters
         (┼, ╬, ║, ╒, and so on) with standard Ascii characters (|, =,
         +, *).  This is designed for use with printers which can't print
         the graphics characters, although the A option takes effect
         whether output is directed to the printer, to a file, or to the
         screen.  This option only affects the graphics characters
         produced by @Compare: if the files being compared contain
         extended Ascii graphics characters, they will not be translated
         when printed.

    R -- sends reports of discrepancies to two files.  The program prompts
         for the names of these files, which default to @Compare.@R@ and
         @Compare.@S@, and which will be overwritten if they already
         exist.  This option was designed to be used on files containing
         data in fields and columns, and it is probably most useful in
         that case, but it works well when used on other files.  This op-
         tion is described more fully in a later section of this document.

    C -- overrides the page breaks which occur whenever the screen in full
         of output, resulting in a continuous scroll of information on the
         screen.  This parameter is only meaningful if P and F parameters
         are not specified, or in other words, it only takes effect if
         output is directed to the screen.

    L -- does a longer search than usual to find matching lines.
    E -- does an extra long search to find matching lines.
         These more thorough searches slow down execution of the program,
         and shouldn't be necessary for most operations.

    B -- suppresses direct video writes, and uses BIOS calls to write to
         the screen.  BIOS calls are slower, but sometimes necessary, such
         as in the case where DESQview requires them to prevent bleeding.

    Q -- quits the program.  If you invoke the program without command
         line parameters, and all you want to do is view the usage
         reminder, enter Q at the options prompt.


Examples of operation:

Two versions of an Ascii document can be compared by typing:
@Compare Ascii1.doc Ascii2.doc

This comparison may be directed to a file by typing:
@Compare /f Ascii1.doc Ascii2.doc

The comparison may be directed to the printer, with the title and high-
lighting suppressed, with the command:
@Compare -PTH Ascii1.doc Ascii2.doc

If only one filename is specified on the command line, it will be
assumed that the second filename is the corresponding .BAK file, if one
exists.  In other words, the following two commands are equivalent:
@Compare Ascii.doc
@Compare Ascii.doc Ascii.bak

If you issue the command "@Compare Ascii.doc", and @Compare can't find
the Ascii.bak file, @Compare will prompt for a second file name.



THE @COMPARE ENVIRONMENT VARIABLE:  ═══════════════════════════════════════

Some of the information in the previous section is modified by the DOS
environment variable @COMPARE, if it exists.  This variable is absolutely
optional, and @Compare will function just fine without it.  However, you
may want to use it to customize @Compare's operation.

It is outside the scope of this document to explain environment variables.
For more information, consult your DOS manual.  Because @Compare doesn't
require the @COMPARE environment variable, you can safely skip this
section if you don't know about the DOS environment.

If @Compare finds the @COMPARE variable in the environment, the environ-
ment string is used to modify @Compare's operation in two ways.

FIRST OF ALL, part of the environment string, as explained below, sup-
plants "bak" as the backup file extension.  As explained in the previous
section, the command "@Compare Ascii.doc" is equivalent to the command
"@Compare Ascii.doc Ascii.bak".  That is, if the user does not specify a
second file name, @Compare assumes that the second file name should be the
backup version of the first file name, and acts accordingly.

Now, let's say your editor creates backup files with an extension other
than .BAK, say .BCK, or .BKP, etc.  Or, let's say you're comparing doubly-
entered data with the report option, and that your first dataset is called
DATA.001 and your second is called DATA.002.  With the @COMPARE environ-
ment variable, you can tell @Compare what to look for as a default second
file extension. In this way, "@Co